====== pureldap Plugin ======

---- plugin ----
description: A new LDAP/AD auth plugin for DokuWiki
author     : Andreas Gohr 
email      : andi@splitbrain.org 
type       : auth
lastupdate : 2023-12-05
compatible : igor, jack jackrum
depends    : 
conflicts  : 
similar    : authad
tags       : activedirectory, ad, ldap, sso, !experimental

downloadurl: https://github.com/splitbrain/dokuwiki-plugin-pureldap/zipball/master
bugtracker : https://github.com/splitbrain/dokuwiki-plugin-pureldap/issues
sourcerepo : https://github.com/splitbrain/dokuwiki-plugin-pureldap/
donationurl: https://donate.dokuwiki.org/pureldap

screenshot_img : 
----

This plugin implements authentication via ActiveDirectory (and possibly other LDAP servers later). It does not require any LDAP support in PHP and aims to have much better performance than the bundled [[authad]] plugin. This is especially true for all operations that do bulk user data requests. LDAP protocol connectivity is provided by the [[https://github.com/FreeDSx/LDAP|FreeDSx LDAP]] library.

This plugin is beta software. Be sure to read the whole of this page before installing it.

===== Background: Limitations of the bundled Plugins =====

DokuWiki includes two plugins that can authenticate users via the LDAP protocol: [[authldap]] and [[authad]]. Despite both plugins doing similar things, both are completely separate and share no code.

While authldap uses the PHP LDAP extension directly, authad makes use of the  [[https://github.com/adldap/adLDAP|adLDAP]] library. There are multiple versions of this library - all slightly incompatible with each other. The authad Plugin uses version 1. The library abstracts away all the LDAP specifics, implements weird Microsoft quirks and makes it easier to configure AD access than doing it manually. However, it also limits the ability to customize the access to unusual AD setups.

Both plugins basically provide the same base features: authenticate users against an LDAP server and make the groups available for ACL management.

Both plugins share a few shortcomings when it comes to performance. This is especially notable when user data of many users needs to be queried.

  - All user data has to be queried individually. Whenever a plugin requires the members of a given group, an additional query has to be made to fetch the user data for each individual member.
  - Already queried user data isn't cached. So if a user's info is used several times, several LDAP queries have to be executed.
  - The performance of the PHP LDAP extension itself isn't stellar either.

There are also quality problems in both plugins

  - the adLDAP library is no longer maintained
  - both plugins differ in functionality
  - there is some code duplication between the plugins
  - no automated tests

===== PureLDAP Feature Comparison =====

The pureLDAP plugin tries to remedy the issues above. Ultimately, the following goals should be met:

  - single code base for LDAP and AD connections
  - strong caching for queried data
  - implement bulk queries
  - implement the full feature set of both old plugins

Implementing all those features does not have to be done right away. It makes sense to first focus on one aspect (like AD connectivity) and implement features step by step.

The table below shows the current state. The plugin implements **all the basic functionality to authenticate with typical Active Directory Setups and has proven to be reliant and performant** in real life setups.


^                                   ^  authldap     ^  authad                ^  pureldap                   ^
| PHP LDAP extension required       |  yes          |  yes                   |  no                         |
| Server Support                    |  any          |  AD only               |  AD only, LDAP planned      |
| Single Sign On                    |  no           |  Kerberos/NTLM         |  Kerberos/NTLM              |
| SSL/TLS Cert Trust Settings       |  via OS only  |  via OS only           |  Plugin Setting             |
| Change Password                   |  no           |  with Admin User only  |  Admin User & Self-Service  |
| Warn on expiring password         |  no           |  yes                   |  yes                        |
| Multi-Domain Support              |  no           |  yes                   |  no                         |
| Fetch additional attributes       |  yes          |  yes                   |  yes                        |
| Custom Attribute-Mapping          |  yes          |  no                    |  no                         |
| Full control on all LDAP queries  |  yes          |  no                    |  no                         |
| Automated Testing                 |  no           |  no                    |  yes                        |
| Group Caching and Bulk Queries    |  no           |  no                    |  yes                        |


===== Installation =====

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

===== Configuration and Migrating from authAD =====

Config parameters are somewhat different from the previous [[authad]] plugin. The config manager should help you out there. The [[authad]] documentation will still help you with setting up SSO etc.

Here's a typical example configuration:

<code>
$conf['plugin']['pureldap']['base_dn'] = 'DC=example,DC=local';
$conf['plugin']['pureldap']['suffix'] = 'example.local';
# DO NOT INCLUDE @ in the suffix, as it will be automatically added
$conf['plugin']['pureldap']['servers'] = array('dc.example.local');
$conf['plugin']['pureldap']['encryption'] = 'tls';
$conf['plugin']['pureldap']['validate'] = 'self';
$conf['plugin']['pureldap']['admin_username'] = 'adminuser';
$conf['plugin']['pureldap']['admin_password'] = 'adminpass';
$conf['plugin']['pureldap']['attributes'] = array('department','office');
$conf['plugin']['pureldap']['primarygroup'] = 'Domain Users';
$conf['plugin']['pureldap']['port'] = '636'; # port information only required if deviating from normal ports (389|636)
$conf['plugin']['pureldap']['recursivegroups'] = 1;
$conf['plugin']['pureldap']['sso'] = 1; # requires webserver setup
</code>

**User and group names** are cleaned less aggressively than in the old plugins. Previously names where mangled to fit DokuWiki page ID requirements, stripping spaces and other special chars. This was a one-way transformation which made it difficult to do reverse lookups (like searching for group members). The pureLDAP plugin will only lowercase user and group names, but keeps them as is otherwise. **Existing ACLs may need adjustments accordingly.**

If manually editing group name mappings in acl.auth.php make sure that authAd space format is convertoed to actual spaces using proper formating.

Example **acl.auth.php** - Groupname mapping of **Domain Users**:
  * AuthAD ACL formatting translates spaces to %5f (underscore _)
<file php acl.auth.php>
WikiDomainUsers: @Domain%5fUsers 16
</file>
  * PureLDAP ACL formatting translates spaces to %20
<file php acl.auth.php>
WikiDomainUsers: @Domain%20Users 16
</file>

**Password Changes** are supported when encryption is used. When a user changes their own password via the user profile, this change will be executed as the user themselves and the Active Directory will apply the appropriate Password Policies.

**Password resets** (where the user forgot their password) will always be executed with the configured administrative user which needs the appropriate permissions to change passwords for arbitrary users. These changes will ignore the password policy. It is recommended to enforce the policy on DokuWiki side using the [[passpolicy]] plugin. If you don't want this feature at all, you can disable password resets in the [[config:disableactions]] option.

===== Next Steps for Development =====

The [[https://github.com/splitbrain/dokuwiki-plugin-pureldap/projects/1|Github Project: Full Feature Set]] provides a rough overview on the next steps that are needed to make the plugin an adequate replacement for the two old plugins. Most importantly, supporting non AD-Setups is currently completely missing.

More work is clearly needed. However, as a private person I have absolutely no use for LDAP or AD connectivity. Setting up test servers etc. and trying to replicate complex corporate setups is nearly impossible. TBH. there is really nothing here that motivates me to implement this except that it would be nice to have and is an interesting challenge - but so are many other things ;-).

So instead of me implementing this in my spare time, it makes more sense for [[https://www.cosmocode.de|CosmoCode]] to implement this. Or to rephrase it: it makes more sense for me to create this while being paid to do so. Doing it at my dayjob also provides me with the support of my colleagues when it comes to coding, research and sysadmin tasks.

In short: If you want to make use of more performant LDAP or AD connectivity in DokuWiki and have the company resources to fund that, please get in contact at <dokuwiki@cosmocode.de>.